The Compressor Capability Structure(IM: QC)

Inside Macintosh: QuickTime Components /

Chapter 4 - Image Compressor Components / Image Compressor Components Reference

The Compressor Capability Structure
Image compressor components use the compressor capability structure to report their capabilities to the Image Compression Manager. Before compressing or decompressing an image, the Image Compression Manager requests this capability information from the component that will be handling the operation by calling the CDPreCompress or CDPreDecompress function provided by that component. The compressor component examines the compression or decompression parameters and indicates any restrictions on its ability to satisfy the request in a formatted compressor capability structure. The Image Compression Manager then manages the operation according to the capabilities of the component.
The CodecCapabilities data type defines the compressor capability structure.
typedef struct {
   long           flags;            /* control information */
   short          wantedPixelSize;  /* pixel depth for component
                                       to use with image */
   short          extendWidth;      /* extension width of image
                                       in pixels */
   short          extendHeight;     /* extension height of image
                                       in pixels */
   short          bandMin;          /* supported minimum 
                                       image band height */
   short          bandInc;          /* common factor of
                                       supported band heights */
   short          pad;              /* reserved */
   unsigned long  time;             /* milliseconds operation
                                       takes to complete */
} CodecCapabilities;

typedef CodecCapabilities *CodecCapabilitiesPtr;
Field Description

flags
Contains flags that contain control information that is used by both the Image Compression Manager and the compressor component. The defined bit positions for this field are discussed later in this section.
wantedPixelSize
Indicates the pixel depth the component can use with the specified image. The component determines the pixel depth of the image for the operation by examining the appropriate pixel map.
extendWidth
Specifies the number of pixels the image must be extended in width. If the component cannot accommodate the image at its
given width, the component may request that the Image Compression Manager extend the width of the image by adding pixels to the right edge of the image. This is sometimes necessary to accommodate the component's block size.
extendHeight
Specifies the number of pixels the image must be extended in height. If the component cannot accommodate the image at its given height the component may request that the Image Compression Manager extend the height of the image by adding pixels to the bottom of the image. This is sometimes necessary to accommodate the component's block size.
bandMin
Contains the minimum image band height supported by the component. Components that can tolerate small values operate under a wider set of memory conditions.
bandInc
Specifies a common factor of supported image band heights. A component may support only image bands that are an even multiple of some number of pixels high. These components report this common factor in the bandInc field. Set this field to 1 if your component supports bands of any size.
pad
Reserved for use by Apple.
time
Indicates the number of milliseconds the operation will take to complete. If the compressor cannot determine this value, it sets this field to 0.
The flags field of the compressor capability structure contains flags that exchange control information between the Image Compression Manager and the compressor component. Components use flags in the low-order 16 bits to indicate their capabilities to the manager. The Image Compression Manager may use flags in the high-order 16 bits to pass control information to the component.
The following flags are defined:
#define codecCanScale            (1L<<0)  /* decompressor scales 
                                             information */
#define codecCanMask             (1L<<1)  /* decompressor applies mask to
                                             image */
#define codecCanMatte            (1L<<2)  /* decompressor blends image using
                                             matte */
#define codecCanTransform        (1L<<3)  /* decompressor works with complex
                                             placement matrices */
#define codecCanTransferMode     (1L<<4)  /* decompressor accepts transfer
                                             mode */
#define codecCanCopyPrev         (1L<<5)  /* compressor updates previous
                                             image buffer */
#define codecCanSpool            (1L<<6)  /* component can use functions to
                                             spool data */
#define codecCanClipVertical     (1L<<7)  /* decompressor clips image 
                                             vertically */
#define codecCanClipRectangular  (1L<<8)  /* decompressor clips image
                                             vertically & horizontally */
#define codecCanRemapColor       (1L<<9)  /* compressor remaps color */
#define codecCanFastDither       (1L<<10) /* compressor supports fast
                                             dithering */
#define codecCanSrcExtract       (1L<<11) /* compressor extracts portion
                                             of source image */
#define codecCanCopyPrevComp     (1L<<12) /* compressor updates previous 
                                             image buffer */
#define codecCanAsync            (1L<<13) /* component can work
                                             asynchronously */
#definecodecCanMakeMask          (1L<<14) /* decompressor makes
                                             modification masks */
#define codecCanShift            (1L<<15) /* component works with pixels 
                                             that are not byte-aligned */
IMPORTANT
The following flags are currently unused by the Image Compression Manager: codecCanClipVertical, codecCanClipRectangular, and codecCanFastDither.
Flag descriptions

codecCanScale
Indicates whether the decompressor can scale the image during decompression. The decompressor sets this flag to 1 to indicate that it can scale the image during decompression. The decompressor sets this flag to 0 if it cannot scale the decompressed image.
codecCanMask
Indicates whether the decompressor can apply a mask to the decompressed image. The decompressor sets this flag to 1 to indicate that it can use a mask to control the image that results from a decompression operation. The decompressor sets this flag to 0 if it cannot work with masks.
codecCanMatte
Indicates whether the decompressor can blend the decompressed image using a matte. The decompressor sets this flag to 1 to indicate that it can use a blend matte during decompression. The decompressor sets this flag to 0 if it cannot use a blend matte.
codecCanTransform
Indicates whether the decompressor can work with complex placement matrixes. The decompressor sets this flag to 1 to indicate that it can work with transformation matrixes during decompression. The decompressor sets this flag to 0 if it cannot work with matrixes.
codecCanTransferMode
Indicates whether the decompressor can accept a transfer mode other than source copy or dither copy when displaying a decompressed image. The decompressor sets this flag to 1 to indicate that it can accept transfer modes; otherwise, the decompressor sets this flag to 0.
codecCanCopyPrev
Indicates whether the compressor can update the previous image buffer during sequence compression. The compressor sets this flag to 1 to indicate that it can update the previous image buffer. The compressor sets this flag to 0 if it cannot update the buffer.
codecCanSpool
Indicates whether the component can use data-loading and data-unloading functions to spool data during decompression and compression operations, respectively. Applications may define data-loading and data-unloading functions to handle images that cannot fit into memory (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information on data-loading and data-unloading functions). The component sets this flag to 1 to indicate that it can use these functions. The component sets this flag to 0 to indicate that it cannot use these functions.
codecCanClipVertical
Indicates whether the decompressor can clip an image vertically during decompression. The decompressor sets this flag to 1 to indicate that it can clip an image vertically. The decompressor sets this flag to 0 to indicate that it cannot clip an image vertically.
codecCanClipRectangular
Indicates whether the decompressor can clip both vertically and horizontally during decompression. The decompressor sets this flag to 1 to indicate that it can clip along both axes. The decompressor sets this flag to 0 to indicate that it cannot clip an image both vertically and horizontally.
codecCanRemapColor
Indicates whether the compressor can remap the colors for an image using color tables. The compressor sets this flag to 1 if it can remap colors. The compressor sets this flag to 0 if it cannot remap colors.
codecCanFastDither
Indicates whether the compressor supports fast dithering.
The compressor sets this flag to 1 if it supports fast dithering. The compressor sets this flag to 0 if it does not support fast dithering. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about fast dithering.
codecCanSrcExtract
Indicates whether the compressor can extract a portion of the source image. The compressor sets this flag to 1 if it can extract a portion of the source image. The compressor sets the flag to 0 if it cannot.
codecCanCopyPrevComp
Indicates whether the compressor can update the previous image buffer during sequence compression using compressed data. The compressor sets this flag to 1 to indicate that it can update the previous image buffer. The compressor sets this flag to 0 if it cannot update the buffer.
codecCanAsync
Indicates whether the component can work asynchronously. The compressor sets this flag to 1 if it can compress and decompress asynchronously; otherwise, it sets this flag to 0.
codecCanMakeMask
Indicates whether the decompressor creates modification masks during decompression. These masks indicate which pixels in the decompressed image differ from the previous image and must therefore be displayed. Such masks are useful only when processing sequences. The decompressor sets this flag to 1 to indicate that it creates modification masks. The decompressor sets this flag to 0 if it does not create such masks.
codecCanShift
Indicates whether the component can work with pixels that are not byte-aligned. This flag is valid only when the source or destination uses fewer than 8 bits per pixel. Components set this flag to 1 if they can read or write pixels that are not byte-aligned. Components set this flag to 0 if pixels must be byte-aligned.